<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Writing serializable models &mdash; django-serializable v0.1 documentation</title>
    <link rel="stylesheet" href="../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '0.1',
        COLLAPSE_MODINDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <link rel="top" title="django-serializable v0.1 documentation" href="../index.html" />
    <link rel="next" title="Using generic views for your serializable models" href="views.html" />
    <link rel="prev" title="Natural keys" href="natural_keys.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="../modindex.html" title="Global Module Index"
             accesskey="M">modules</a> |</li>
        <li class="right" >
          <a href="views.html" title="Using generic views for your serializable models"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="natural_keys.html" title="Natural keys"
             accesskey="P">previous</a> |</li>
        <li><a href="../index.html">django-serializable v0.1 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="module-serializable.tests.testmodels.models">
<h1>Writing serializable models<a class="headerlink" href="#module-serializable.tests.testmodels.models" title="Permalink to this headline">¶</a></h1>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">First the package has to be on your python path.</p>
</div>
<p>Let’s see quick examples of models using our serialization support.</p>
<div class="section" id="general-case">
<span id="serialization-examples"></span><h2>General case<a class="headerlink" href="#general-case" title="Permalink to this headline">¶</a></h2>
<p>Here is some models definition, pay attention to the class attribute <cite>nk_field_names</cite> that corresponds with our natural key :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Author</span> <span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">firstname</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    <span class="n">lastname</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;firstname&quot;</span><span class="p">,</span> <span class="s">&quot;lastname&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;firstname&quot;</span><span class="p">,</span> <span class="s">&quot;lastname&quot;</span><span class="p">]</span>
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;firstname&quot;</span><span class="p">,</span> <span class="s">&quot;lastname&quot;</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Book</span> <span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">author</span> <span class="o">=</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="n">Author</span><span class="p">)</span>
    <span class="n">title</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    <span class="n">comments</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;author&quot;</span><span class="p">,</span> <span class="s">&quot;title&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;author&quot;</span><span class="p">,</span> <span class="s">&quot;title&quot;</span><span class="p">,</span> <span class="s">&quot;pk&quot;</span><span class="p">]</span>
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;pk&quot;</span><span class="p">,)</span>
</pre></div>
</div>
<p>Then how to use the serialization features for these objects :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">Author</span><span class="p">(</span><span class="n">firstname</span><span class="o">=</span><span class="s">&quot;John&quot;</span><span class="p">,</span> <span class="n">lastname</span><span class="o">=</span><span class="s">&quot;Steinbeck&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">a</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span> <span class="o">=</span> <span class="n">Book</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s">&quot;Grapes of Wrath&quot;</span><span class="p">,</span> <span class="n">author</span><span class="o">=</span><span class="n">a</span><span class="p">,</span> <span class="n">comments</span><span class="o">=</span><span class="s">&quot;great great great&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
</pre></div>
</div>
<p>Serializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">b</span><span class="o">.</span><span class="n">serialize</span><span class="p">()</span> <span class="o">==</span> <span class="p">{</span><span class="s">&#39;title&#39;</span><span class="p">:</span> <span class="s">u&#39;Grapes of Wrath&#39;</span><span class="p">,</span> <span class="s">&#39;author&#39;</span><span class="p">:</span> <span class="p">(</span><span class="s">&#39;John&#39;</span><span class="p">,</span> <span class="s">&#39;Steinbeck&#39;</span><span class="p">)}</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Deserializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">bd</span> <span class="o">=</span> <span class="n">Book</span><span class="o">.</span><span class="n">deserialize</span><span class="p">({</span><span class="s">&#39;author&#39;</span><span class="p">:</span> <span class="p">(</span><span class="s">&#39;John&#39;</span><span class="p">,</span> <span class="s">&#39;Steinbeck&#39;</span><span class="p">),</span> <span class="s">&#39;title&#39;</span><span class="p">:</span> <span class="s">&#39;In Dubious Battle&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bd</span><span class="o">.</span><span class="n">author</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="n">a</span><span class="o">.</span><span class="n">id</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bd</span><span class="o">.</span><span class="n">title</span>
<span class="go">u&#39;In Dubious Battle&#39;</span>
</pre></div>
</div>
<p>And updating :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">bd</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s">&#39;title&#39;</span><span class="p">:</span> <span class="s">&#39;Of mice and men&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bd</span><span class="o">.</span><span class="n">title</span>
<span class="go">u&#39;Of mice and men&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">bd</span><span class="o">.</span><span class="n">author</span> <span class="o">==</span> <span class="n">a</span>
<span class="go">True</span>
</pre></div>
</div>
<p>So it&#8217;s very simple... Notice that the foreign key is never directly implied. However, if you want anyways to serialize the primary key of an object or use it as the natural key, use the property <cite>&#8216;pk&#8217;</cite>.</p>
</div>
<div class="section" id="with-a-single-field-as-natural-key">
<h2>With a single field as natural key<a class="headerlink" href="#with-a-single-field-as-natural-key" title="Permalink to this headline">¶</a></h2>
<p>Now if you want to use only one field as the natural key, there is a slight difference. Here&#8217;s another model :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Dish</span> <span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,)</span>

<span class="k">class</span> <span class="nc">Guy</span> <span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">pseudo</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    <span class="n">favourite_dish</span> <span class="o">=</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="n">Dish</span><span class="p">)</span>

    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;pseudo&quot;</span><span class="p">,</span> <span class="s">&quot;favourite_dish&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;pseudo&quot;</span><span class="p">,</span> <span class="s">&quot;favourite_dish&quot;</span><span class="p">]</span>
</pre></div>
</div>
<p>Some objects :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">Dish</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;cheese&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span> <span class="o">=</span> <span class="n">Guy</span><span class="p">(</span><span class="n">pseudo</span><span class="o">=</span><span class="s">&quot;Johnny&quot;</span><span class="p">,</span> <span class="n">favourite_dish</span><span class="o">=</span><span class="n">d</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
</pre></div>
</div>
<p>Serializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">g</span><span class="o">.</span><span class="n">serialize</span><span class="p">()</span> <span class="o">==</span> <span class="p">{</span><span class="s">&#39;pseudo&#39;</span><span class="p">:</span> <span class="s">u&#39;Johnny&#39;</span><span class="p">,</span> <span class="s">&#39;favourite_dish&#39;</span><span class="p">:</span> <span class="s">&#39;cheese&#39;</span><span class="p">}</span>
<span class="go">True</span>
</pre></div>
</div>
<p>And deserializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">gd</span> <span class="o">=</span> <span class="n">Guy</span><span class="o">.</span><span class="n">deserialize</span><span class="p">({</span><span class="s">&#39;pseudo&#39;</span><span class="p">:</span> <span class="s">u&#39;Jack&#39;</span><span class="p">,</span> <span class="s">&#39;favourite_dish&#39;</span><span class="p">:</span> <span class="s">&#39;cheese&#39;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gd</span><span class="o">.</span><span class="n">favourite_dish</span><span class="o">.</span><span class="n">id</span> <span class="o">==</span> <span class="n">d</span><span class="o">.</span><span class="n">id</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">gd</span><span class="o">.</span><span class="n">pseudo</span>
<span class="go">u&#39;Jack&#39;</span>
</pre></div>
</div>
<p>That&#8217;s right ... in case there&#8217;s only one field as the natural key, you don&#8217;t have to bother manipulating tuples for (de)serialization operations. Only <tt class="xref docutils literal"><span class="pre">nk_field_names</span></tt> must still be a tuple. If you want anyways to use a tuple for the deserialization (then with a single element), it will work as well.</p>
</div>
<div class="section" id="nested-relationships-deep-serialization">
<h2>Nested relationships / deep serialization<a class="headerlink" href="#nested-relationships-deep-serialization" title="Permalink to this headline">¶</a></h2>
<p>No matter how deep the relationships are, the natural keys are always used. For example with these models :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">Dynasty</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">]</span>
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,)</span>

<span class="k">class</span> <span class="nc">Family</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    <span class="n">dynasty</span> <span class="o">=</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="n">Dynasty</span><span class="p">)</span>
    
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;dynasty&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;dynasty&quot;</span><span class="p">]</span>
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;dynasty&quot;</span><span class="p">)</span>

<span class="k">class</span> <span class="nc">Person</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">family</span> <span class="o">=</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="n">Family</span><span class="p">)</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;family&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;family&quot;</span><span class="p">]</span>
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;name&quot;</span><span class="p">,</span> <span class="s">&quot;family&quot;</span><span class="p">)</span>
    
<span class="k">class</span> <span class="nc">Short</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">person</span> <span class="o">=</span> <span class="n">ForeignKey</span><span class="p">(</span><span class="n">Person</span><span class="p">)</span>
    <span class="n">brand</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;brand&quot;</span><span class="p">,</span> <span class="s">&quot;person&quot;</span><span class="p">]</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;brand&quot;</span><span class="p">,</span> <span class="s">&quot;person&quot;</span><span class="p">]</span>
    <span class="n">nk_field_names</span> <span class="o">=</span> <span class="p">(</span><span class="s">&quot;brand&quot;</span><span class="p">,</span><span class="s">&quot;person&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Some instances :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="n">Dynasty</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;Capetians&quot;</span><span class="p">)</span> <span class="p">;</span> <span class="n">d</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">Family</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s">&quot;Johnson&quot;</span><span class="p">,</span> <span class="n">dynasty</span><span class="o">=</span><span class="n">d</span><span class="p">)</span> <span class="p">;</span> <span class="n">f</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">Person</span><span class="p">(</span><span class="n">family</span><span class="o">=</span><span class="n">f</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">&quot;Steven&quot;</span><span class="p">)</span> <span class="p">;</span> <span class="n">p</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">s</span> <span class="o">=</span> <span class="n">Short</span><span class="p">(</span><span class="n">person</span><span class="o">=</span><span class="n">p</span><span class="p">,</span> <span class="n">brand</span><span class="o">=</span><span class="s">&quot;Calvin Klein&quot;</span><span class="p">)</span> <span class="p">;</span> <span class="n">s</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
</pre></div>
</div>
<p>Serializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">s</span><span class="o">.</span><span class="n">serialize</span><span class="p">()</span> <span class="o">==</span> <span class="p">{</span><span class="s">&quot;brand&quot;</span><span class="p">:</span> <span class="s">&quot;Calvin Klein&quot;</span><span class="p">,</span> <span class="s">&quot;person&quot;</span><span class="p">:</span> <span class="p">(</span><span class="s">&quot;Steven&quot;</span><span class="p">,</span> <span class="p">(</span><span class="s">&quot;Johnson&quot;</span><span class="p">,</span> <span class="s">&quot;Capetians&quot;</span><span class="p">))}</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Deserializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">sd</span> <span class="o">=</span> <span class="n">Short</span><span class="o">.</span><span class="n">deserialize</span><span class="p">({</span><span class="s">&quot;brand&quot;</span><span class="p">:</span> <span class="s">&quot;Pierre Cardin&quot;</span><span class="p">,</span> <span class="s">&quot;person&quot;</span><span class="p">:</span> <span class="p">(</span><span class="s">&quot;Steven&quot;</span><span class="p">,</span> <span class="p">(</span><span class="s">&quot;Johnson&quot;</span><span class="p">,</span> <span class="s">&quot;Capetians&quot;</span><span class="p">))})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">sd</span><span class="o">.</span><span class="n">person</span> <span class="o">==</span> <span class="n">p</span>
<span class="go">True</span>
</pre></div>
</div>
</div>
<div class="section" id="serializing-deserializing-properties">
<h2>Serializing/deserializing properties<a class="headerlink" href="#serializing-deserializing-properties" title="Permalink to this headline">¶</a></h2>
<p>The (de)serialization works exactly the same with all the properties (notably with the <cite>&#8216;pk&#8217;</cite> property) :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">PropertyFields</span> <span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Serializable</span><span class="p">)</span> <span class="p">:</span>
    <span class="n">deserialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&quot;a_field_property&quot;</span><span class="p">]</span>
    <span class="n">serialize_fields</span> <span class="o">=</span> <span class="p">[</span><span class="s">&#39;a_field_property&#39;</span><span class="p">]</span>
    
    <span class="n">a_field</span> <span class="o">=</span> <span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">100</span><span class="p">)</span>
    
    <span class="nd">@property</span>
    <span class="k">def</span> <span class="nf">a_field_property</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">a_field</span>

    <span class="nd">@a_field_property.setter</span>
    <span class="k">def</span> <span class="nf">a_field_property</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">a_field</span> <span class="o">=</span> <span class="n">value</span>
</pre></div>
</div>
<p>Some objects :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">pf</span> <span class="o">=</span> <span class="n">PropertyFields</span><span class="p">(</span><span class="n">a_field</span><span class="o">=</span><span class="s">&#39;test1&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>Serializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">pf</span><span class="o">.</span><span class="n">serialize</span><span class="p">()</span> <span class="o">==</span> <span class="p">{</span><span class="s">&#39;a_field_property&#39;</span><span class="p">:</span> <span class="s">&#39;test1&#39;</span><span class="p">}</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Deserializing :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">pf</span> <span class="o">=</span> <span class="n">PropertyFields</span><span class="o">.</span><span class="n">deserialize</span><span class="p">({</span><span class="s">&quot;a_field_property&quot;</span><span class="p">:</span> <span class="s">&quot;test test test&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pf</span><span class="o">.</span><span class="n">a_field_property</span>
<span class="go">&#39;test test test&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">pf</span><span class="o">.</span><span class="n">a_field</span>
<span class="go">&#39;test test test&#39;</span>
</pre></div>
</div>
</div>
<div class="section" id="using-mixins-instead-of-serializable-as-a-base-class">
<h2>Using mixins instead of <tt class="xref docutils literal"><span class="pre">Serializable</span></tt> as a base class<a class="headerlink" href="#using-mixins-instead-of-serializable-as-a-base-class" title="Permalink to this headline">¶</a></h2>
<p>If you don&#8217;t want to use <tt class="xref docutils literal"><span class="pre">Serializable</span></tt> as a base class for your models, you should use <tt class="xref docutils literal"><span class="pre">SerializableMixin</span></tt> as a mixin. For example :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyModel</span><span class="p">(</span><span class="n">MyBaseModel</span><span class="p">,</span> <span class="n">SerializableMixin</span><span class="p">):</span>
    
    <span class="c">#default manager must have a &#39;get_by_natural_key&#39; method</span>
    <span class="n">objects</span> <span class="o">=</span> <span class="n">SerializableManager</span><span class="p">()</span>
    
    <span class="c">#your code here</span>
</pre></div>
</div>
<p>If you don&#8217;t want to use <tt class="xref docutils literal"><span class="pre">SerializableManager</span></tt> as your default manager neither, you can also define your custom manager and use the <tt class="xref docutils literal"><span class="pre">:class:`SerializableManagerMixin</span></tt>. For example :</p>
<div class="highlight-python"><pre>class MyManager(MyBaseManager, SerializableManagerMixin):
    
    #your code here</pre>
</div>
</div>
<div class="section" id="module-serializable.models">
<h2>Package members &#8211; <tt class="xref docutils literal"><span class="pre">serializable.models</span></tt><a class="headerlink" href="#module-serializable.models" title="Permalink to this headline">¶</a></h2>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This doesn&#8217;t work with the version 1.1 of Django. The version 1.2 must be used because the serializers doesn&#8217;t have the features we require in django 1.1 (especially the <cite>use_natural_keys</cite> feature).</p>
</div>
<dl class="class">
<dt id="serializable.models.SerializableMixin">
<em class="property">class </em><tt class="descclassname">serializable.models.</tt><tt class="descname">SerializableMixin</tt><a class="headerlink" href="#serializable.models.SerializableMixin" title="Permalink to this definition">¶</a></dt>
<dd><p>Mixin for using with your models, in case you don&#8217;t want to use <a title="serializable.models.Serializable" class="reference internal" href="#serializable.models.Serializable"><tt class="xref docutils literal"><span class="pre">Serializable</span></tt></a> as a base class for your models. Example of use :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyModel</span><span class="p">(</span><span class="n">Model</span><span class="p">,</span> <span class="n">SerializableMixin</span><span class="p">):</span>
    <span class="o">...</span>
</pre></div>
</div>
<dl class="attribute">
<dt id="serializable.models.SerializableMixin.serialize_fields">
<tt class="descname">serialize_fields</tt><a class="headerlink" href="#serializable.models.SerializableMixin.serialize_fields" title="Permalink to this definition">¶</a></dt>
<dd>This class attribute is a list of <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/functions.html#str"><tt class="xref docutils literal"><span class="pre">str</span></tt></a> which are the names of fields/properties that should be serialized when serializing an instance.</dd></dl>

<dl class="attribute">
<dt id="serializable.models.SerializableMixin.deserialize_fields">
<tt class="descname">deserialize_fields</tt><a class="headerlink" href="#serializable.models.SerializableMixin.deserialize_fields" title="Permalink to this definition">¶</a></dt>
<dd>This class attribute is a list of <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/functions.html#str"><tt class="xref docutils literal"><span class="pre">str</span></tt></a> which are the names of fields/properties that should be deserialized when deserializing data into an instance.</dd></dl>

<dl class="attribute">
<dt id="serializable.models.SerializableMixin.nk_field_names">
<tt class="descname">nk_field_names</tt><a class="headerlink" href="#serializable.models.SerializableMixin.nk_field_names" title="Permalink to this definition">¶</a></dt>
<dd><p>This class attribute is a tuple of <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/functions.html#str"><tt class="xref docutils literal"><span class="pre">str</span></tt></a>. It is the &#8216;blueprint&#8217; of natural keys for a class. This means that the values in every tuple that is considered to be the natural key of an instance of this class, map to the field names in this blueprint. Reciprocally, to generate the natural key for any instance, this blueprint is used. See <a class="reference internal" href="#serialization-examples"><em>some examples</em></a></p>
<div class="admonition attention">
<p class="first admonition-title">Attention</p>
<p class="last">If this tuple contains only one element, the natural key generated will be a simple <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/functions.html#str"><tt class="xref docutils literal"><span class="pre">str</span></tt></a> instead of a <a title="(in Python v2.6)" class="reference external" href="http://docs.python.org/library/functions.html#tuple"><tt class="xref docutils literal"><span class="pre">tuple</span></tt></a>.</p>
</div>
</dd></dl>

<dl class="classmethod">
<dt id="serializable.models.SerializableMixin.deserialize">
<em class="property">classmethod </em><tt class="descname">deserialize</tt><big>(</big><em>data</em><big>)</big><a class="headerlink" href="#serializable.models.SerializableMixin.deserialize" title="Permalink to this definition">¶</a></dt>
<dd><p>Fetches, in the parameter <cite>data</cite>, only the fields/properties that are also referenced in the class attribute <a title="serializable.models.SerializableMixin.deserialize_fields" class="reference internal" href="#serializable.models.SerializableMixin.deserialize_fields"><tt class="xref docutils literal"><span class="pre">deserialize_fields</span></tt></a>, and returns a new object (not yet saved in the database) with the fields fetched. The foreign keys must be entered as natural keys, they will be matched to actual objects according to the <a title="serializable.models.SerializableMixin.nk_field_names" class="reference internal" href="#serializable.models.SerializableMixin.nk_field_names"><tt class="xref docutils literal"><span class="pre">nk_field_names</span></tt></a> of the foreign classes.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Parameter:</th><td class="field-body"><p class="first"><em>data</em> &#8211; <em>{field_name : field_value}</em></p>
</td>
</tr>
<tr class="field"><th class="field-name">Raises:</th><td class="field-body"><p class="first"><a title="serializable.models.DeserializationError" class="reference internal" href="#serializable.models.DeserializationError"><tt class="xref docutils literal"><span class="pre">DeserializationError</span></tt></a> in three different cases :</p>
<ul class="last simple">
<li>if a natural key provided in <cite>data</cite> doesn&#8217;t have enough values or has too much, to be mapped with <a title="serializable.models.SerializableMixin.nk_field_names" class="reference internal" href="#serializable.models.SerializableMixin.nk_field_names"><tt class="xref docutils literal"><span class="pre">nk_field_names</span></tt></a></li>
<li>if a natural key yielded multiple results</li>
<li>if a natural key yielded no result</li>
<li>trying to deserialize a field/property that hasn&#8217;t been initialized, or doesn&#8217;t exist</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="serializable.models.SerializableMixin.serialize">
<tt class="descname">serialize</tt><big>(</big><big>)</big><a class="headerlink" href="#serializable.models.SerializableMixin.serialize" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a dictionnary containing only the calling object&#8217;s fields and properties that are referenced in the class attribute <a title="serializable.models.SerializableMixin.serialize_fields" class="reference internal" href="#serializable.models.SerializableMixin.serialize_fields"><tt class="xref docutils literal"><span class="pre">serialize_fields</span></tt></a>. The returned dictionnary has the following format <em>{field_name : field_value}</em>. The foreign keys are replaced by natural keys generated according to <a title="serializable.models.SerializableMixin.nk_field_names" class="reference internal" href="#serializable.models.SerializableMixin.nk_field_names"><tt class="xref docutils literal"><span class="pre">nk_field_names</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Raise:</th><td class="field-body"><a title="serializable.models.SerializationError" class="reference internal" href="#serializable.models.SerializationError"><tt class="xref docutils literal"><span class="pre">SerializationError</span></tt></a> if trying to serialize an field/property that doesn&#8217;t exist.</td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="method">
<dt id="serializable.models.SerializableMixin.update">
<tt class="descname">update</tt><big>(</big><em>data</em><big>)</big><a class="headerlink" href="#serializable.models.SerializableMixin.update" title="Permalink to this definition">¶</a></dt>
<dd>Updates the calling object with the data passed as a parameter. This method works exactly as <tt class="xref docutils literal"><span class="pre">Serializable.deserialize()</span></tt>, except that no new object is created. The changes introduced on the calling object are not yet saved in the database.</dd></dl>

<dl class="method">
<dt id="serializable.models.SerializableMixin.natural_key">
<tt class="descname">natural_key</tt><big>(</big><big>)</big><a class="headerlink" href="#serializable.models.SerializableMixin.natural_key" title="Permalink to this definition">¶</a></dt>
<dd><p>This method returns what is considered to be the <em>natural key</em> of the calling object.</p>
<p>There is no need to override it, as it uses the attribute <a title="serializable.models.SerializableMixin.nk_field_names" class="reference internal" href="#serializable.models.SerializableMixin.nk_field_names"><tt class="xref docutils literal"><span class="pre">nk_field_names</span></tt></a> as a blueprint for automatic <cite>natural key</cite> generation.</p>
</dd></dl>

</dd></dl>

<dl class="class">
<dt id="serializable.models.SerializableManagerMixin">
<em class="property">class </em><tt class="descclassname">serializable.models.</tt><tt class="descname">SerializableManagerMixin</tt><a class="headerlink" href="#serializable.models.SerializableManagerMixin" title="Permalink to this definition">¶</a></dt>
<dd><p>Mixin for using with your custom managers, in case you don&#8217;t want to use <a title="serializable.models.SerializableManager" class="reference internal" href="#serializable.models.SerializableManager"><tt class="xref docutils literal"><span class="pre">SerializableManager</span></tt></a> as a default manager for your models. Example of use :</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyManager</span><span class="p">(</span><span class="n">Manager</span><span class="p">,</span> <span class="n">SerializableManagerMixin</span><span class="p">):</span>
    <span class="o">...</span>
</pre></div>
</div>
</dd></dl>

<dl class="class">
<dt id="serializable.models.Serializable">
<em class="property">class </em><tt class="descclassname">serializable.models.</tt><tt class="descname">Serializable</tt><big>(</big><em>*args</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#serializable.models.Serializable" title="Permalink to this definition">¶</a></dt>
<dd>A base class for adding serialization support to models. This is an abstract class, and should be subclassed for use. Subclassing only implies overriding the attributes <tt class="xref docutils literal"><span class="pre">serialize_fields</span></tt>, <tt class="xref docutils literal"><span class="pre">deserialize_fields</span></tt> and <tt class="xref docutils literal"><span class="pre">nk_field_names</span></tt></dd></dl>

<dl class="class">
<dt id="serializable.models.SerializableManager">
<em class="property">class </em><tt class="descclassname">serializable.models.</tt><tt class="descname">SerializableManager</tt><a class="headerlink" href="#serializable.models.SerializableManager" title="Permalink to this definition">¶</a></dt>
<dd>This manager should be the default manager of any subclass of <a title="serializable.models.Serializable" class="reference internal" href="#serializable.models.Serializable"><tt class="xref docutils literal"><span class="pre">Serializable</span></tt></a> or <a title="serializable.models.SerializableMixin" class="reference internal" href="#serializable.models.SerializableMixin"><tt class="xref docutils literal"><span class="pre">SerializableMixin</span></tt></a>.</dd></dl>

<dl class="exception">
<dt id="serializable.models.DeserializationError">
<em class="property">exception </em><tt class="descclassname">serializable.models.</tt><tt class="descname">DeserializationError</tt><a class="headerlink" href="#serializable.models.DeserializationError" title="Permalink to this definition">¶</a></dt>
<dd>This error is thrown in case a deserialization operation failed.</dd></dl>

<dl class="exception">
<dt id="serializable.models.SerializationError">
<em class="property">exception </em><tt class="descclassname">serializable.models.</tt><tt class="descname">SerializationError</tt><a class="headerlink" href="#serializable.models.SerializationError" title="Permalink to this definition">¶</a></dt>
<dd>This error is thrown in case a serialization operation failed.</dd></dl>

</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <h3><a href="../index.html">Table Of Contents</a></h3>
            <ul>
<li><a class="reference external" href="#">Writing serializable models</a><ul>
<li><a class="reference external" href="#general-case">General case</a></li>
<li><a class="reference external" href="#with-a-single-field-as-natural-key">With a single field as natural key</a></li>
<li><a class="reference external" href="#nested-relationships-deep-serialization">Nested relationships / deep serialization</a></li>
<li><a class="reference external" href="#serializing-deserializing-properties">Serializing/deserializing properties</a></li>
<li><a class="reference external" href="#using-mixins-instead-of-serializable-as-a-base-class">Using mixins instead of <tt class="docutils literal"><span class="pre">Serializable</span></tt> as a base class</a></li>
<li><a class="reference external" href="#module-serializable.models">Package members &#8211; <tt class="docutils literal"><span class="pre">serializable.models</span></tt></a></li>
</ul>
</li>
</ul>

            <h4>Previous topic</h4>
            <p class="topless"><a href="natural_keys.html"
                                  title="previous chapter">Natural keys</a></p>
            <h4>Next topic</h4>
            <p class="topless"><a href="views.html"
                                  title="next chapter">Using generic views for your serializable models</a></p>
            <h3>This Page</h3>
            <ul class="this-page-menu">
              <li><a href="../_sources/doc_pages/models.txt"
                     rel="nofollow">Show Source</a></li>
            </ul>
          <div id="searchbox" style="display: none">
            <h3>Quick search</h3>
              <form class="search" action="../search.html" method="get">
                <input type="text" name="q" size="18" />
                <input type="submit" value="Go" />
                <input type="hidden" name="check_keywords" value="yes" />
                <input type="hidden" name="area" value="default" />
              </form>
              <p class="searchtip" style="font-size: 90%">
              Enter search terms or a module, class or function name.
              </p>
          </div>
          <script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="../genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="../modindex.html" title="Global Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="views.html" title="Using generic views for your serializable models"
             >next</a> |</li>
        <li class="right" >
          <a href="natural_keys.html" title="Natural keys"
             >previous</a> |</li>
        <li><a href="../index.html">django-serializable v0.1 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer">
      &copy; Copyright 2010, Sebastien Piquemal.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.4.
    </div>
  </body>
</html>